lib: brush up some docs

diff --git a/rust-bindings/rust/src/repo_checkout_at_options.rs b/rust-bindings/rust/src/repo_checkout_at_options.rs
index a1cd37d9f6def0e97e673af69d0459ad39afc500..2a570c58b41f259979efb6907bfcdbe4c6db7c7a 100644 (file)
--- a/rust-bindings/rust/src/repo_checkout_at_options.rs
+++ b/rust-bindings/rust/src/repo_checkout_at_options.rs
@@ -20,6 +20,15 @@ pub struct RepoCheckoutAtOptions {
     pub force_copy_zerosized: bool,
     pub subpath: Option<PathBuf>,
     pub devino_to_csum_cache: Option<RepoDevInoCache>,
+    /// A callback function to decide which files and directories will be checked out from the
+    /// repo. See the documentation on [RepoCheckoutFilter](struct.RepoCheckoutFilter.html) for more
+    /// information on the signature.
+    ///
+    /// # Panics
+    /// This callback may not panic. If it does, `abort()` will be called to avoid unwinding across
+    /// an FFI boundary and into the libostree C code (which is Undefined Behavior). If you prefer to
+    /// swallow the panic rather than aborting, you can use `std::panic::catch_unwind` inside your
+    /// callback to catch and silence any panics that occur.
     pub filter: Option<RepoCheckoutFilter>,
     pub sepolicy: Option<SePolicy>,
     pub sepolicy_prefix: Option<String>,

diff --git a/rust-bindings/rust/src/repo_checkout_at_options/repo_checkout_filter.rs b/rust-bindings/rust/src/repo_checkout_at_options/repo_checkout_filter.rs
index cb8190e43fdf5555044247b39f1b0d63d5cd5227..4d2fe7319bbed87fb15eb39d95d66415843dfc05 100644 (file)
--- a/rust-bindings/rust/src/repo_checkout_at_options/repo_checkout_filter.rs
+++ b/rust-bindings/rust/src/repo_checkout_at_options/repo_checkout_filter.rs
@@ -87,6 +87,8 @@ unsafe extern "C" fn filter_trampoline(
     result.to_glib()
 }
 
+/// Unwind-safe trampoline to call the Rust filter callback. See [filter_trampoline](fn.filter_trampoline.html).
+/// This function additionally catches panics and aborts to avoid unwinding into C code.
 pub(super) unsafe extern "C" fn filter_trampoline_unwindsafe(
     repo: *mut OstreeRepo,
     path: *const c_char,
@@ -102,6 +104,9 @@ pub(super) unsafe extern "C" fn filter_trampoline_unwindsafe(
     })
 }
 
+/// Print a panic message and the value to stderr, if we can.
+///
+/// If the panic value is either `&str` or `String`, we print it. Otherwise, we don't.
 fn print_panic(panic: Box<dyn Any>) {
     eprintln!("A Rust callback invoked by C code panicked.");
     eprintln!("Unwinding across FFI boundaries is Undefined Behavior so abort() will be called.");